home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Resources / Audio, Video & Photo / Songbird 0.7.0 / Songbird_0.7.0_windows-i686-msvc8.exe / jsmodules / SBDataRemoteUtils.jsm < prev    next >
Text File  |  2008-08-06  |  9KB  |  298 lines
  1. /* -*- Mode: Java; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* vim: set sw=2 :miv */
  3. /*
  4. //
  5. // BEGIN SONGBIRD GPL
  6. //
  7. // This file is part of the Songbird web player.
  8. //
  9. // Copyright(c) 2005-2008 POTI, Inc.
  10. // http://songbirdnest.com
  11. //
  12. // This file may be licensed under the terms of of the
  13. // GNU General Public License Version 2 (the "GPL").
  14. //
  15. // Software distributed under the License is distributed
  16. // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
  17. // express or implied. See the GPL for the specific language
  18. // governing rights and limitations.
  19. //
  20. // You should have received a copy of the GPL along with this
  21. // program. If not, go to http://www.gnu.org/licenses/gpl.html
  22. // or write to the Free Software Foundation, Inc.,
  23. // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  24. //
  25. // END SONGBIRD GPL
  26. //
  27.  */
  28.  
  29. /**
  30.  * \file  SBDataRemoteUtils.jsm
  31.  * \brief Javascript source for the Songbird data remote utility services.
  32.  */
  33.  
  34. //------------------------------------------------------------------------------
  35. //
  36. // Songbird data remote utility JSM configuration.
  37. //
  38. //------------------------------------------------------------------------------
  39.  
  40. EXPORTED_SYMBOLS =
  41. [
  42.   "SBDataGetStringValue",
  43.   "SBDataGetIntValue",
  44.   "SBDataGetBoolValue",
  45.   "SBDataSetStringValue",
  46.   "SBDataSetBoolValue",
  47.   "SBDataSetIntValue",
  48.   "SBDataIncrementValue",
  49.   "SBDataDecrementValue",
  50.   "SBDataToggleBoolValue",
  51.   "SBDataFireEvent"
  52. ];
  53.  
  54.  
  55. //------------------------------------------------------------------------------
  56. //
  57. // Songbird data remote utility defs.
  58. //
  59. //------------------------------------------------------------------------------
  60.  
  61. // Component manager defs.
  62. if (typeof(Cc) == "undefined")
  63.   var Cc = Components.classes;
  64. if (typeof(Ci) == "undefined")
  65.   var Ci = Components.interfaces;
  66. if (typeof(Cr) == "undefined")
  67.   var Cr = Components.results;
  68. if (typeof(Cu) == "undefined")
  69.   var Cu = Components.utils;
  70.  
  71.  
  72. //------------------------------------------------------------------------------
  73. //
  74. // sbIDataRemote wrapper
  75. //
  76. //  This object provides the ability to set key-value pairs
  77. //  into a global "data store," and to have various callback
  78. //  effects occur when anyone changes an observed value.
  79. //
  80. //  The callback binding can be placed on a dom element to
  81. //  change its properties or attributes based upon the value
  82. //  (either directly, or as a boolean, and/or as the result
  83. //  of a given evaluation expression).
  84. //
  85. //  The mozilla preferences system is used as the underlying
  86. //  data storage layer to power this interface.  Because the
  87. //  preferences are available to all open windows in xulrunner,
  88. //  these data remotes should function as globals across
  89. //  the application.  This is both powerful and dangerous, and
  90. //  while this interface is available to all, everyone should
  91. //  be very careful to properly namespace their data strings.
  92. //
  93. //  SBDataBindElementProperty Param List:
  94. //   key  - The data ID to bind upon
  95. //   elem - The element ID to be bound
  96. //   attr - The name of the property or attribute to change
  97. //   bool - Optionally assign the data as BOOLEAN data (true/false props,
  98. //          "true"/"false" attrs)
  99. //   not  - Optionally assign the data as a boolean NOT of the value
  100. //   eval - Optionally apply an eval string where `value = eval( eval_string );`
  101. //XXXeps add data remote DOM utilities.
  102. //
  103. //------------------------------------------------------------------------------
  104.  
  105. /**
  106.  * \brief Create a new data remote object.
  107.  *
  108.  * \param aKey - The string identifier for the data to watch
  109.  * \param aRoot - OPTIONAL - If present this defines a prefix to the key
  110.  *
  111.  * \return - A data remote object.
  112.  */
  113.  
  114. function SB_NewDataRemote( aKey, aRoot )
  115. {
  116.   var dataRemote = Cc["@songbirdnest.com/Songbird/DataRemote;1"]
  117.                      .createInstance(Ci.sbIDataRemote);
  118.   dataRemote.init( aKey, aRoot );
  119.   return dataRemote;
  120. }
  121.  
  122. /**
  123.  * \brief Get the value of the data in string format.
  124.  *
  125.  * \param aKey - The string identifier for the data to be changed.
  126.  * \return - The string value of the data. If the data has not been set the
  127.  *           return value will be the empty string ("");
  128.  * \sa DatatRemote
  129.  */
  130. function SBDataGetStringValue( aKey )
  131. {
  132.   var data = SB_NewDataRemote( aKey, null );
  133.   return data.stringValue;
  134. }
  135.  
  136. /**
  137.  * \brief Get the value of the data in integer format
  138.  *
  139.  * \param aKey - The string identifier for the data to be changed.
  140.  * \return - The integer value of the data. If the data has not been set or
  141.  *           the data is not convertible to an integer the return value will
  142.  *           be NaN.
  143.  * \sa DatatRemote
  144.  */
  145. function SBDataGetIntValue( aKey )
  146. {
  147.   var data = SB_NewDataRemote( aKey, null );
  148.   return data.intValue;
  149. }
  150.  
  151. /**
  152.  * \brief Get the value of the data in boolean format.
  153.  *
  154.  * \param aKey - The string identifier for the data to be retrieved.
  155.  * \return - The boolean value of the data.
  156.  * \sa DatatRemote
  157.  */
  158. function SBDataGetBoolValue( aKey )
  159. {
  160.   var data = SB_NewDataRemote( aKey, null );
  161.   return data.boolValue;
  162. }
  163.  
  164. /**
  165.  * \brief Set a string value.
  166.  * Changes the value of the data remote to the boolean passed in, regardless
  167.  *   of its value before.
  168.  *
  169.  * \param aKey - The string identifier for the data to be changed.
  170.  * \param aBoolValue - A boolean value.
  171.  * \return - The new value of the data.
  172.  * \sa DatatRemote
  173.  */
  174. function SBDataSetStringValue( aKey, aStringValue )
  175. {
  176.   var data = SB_NewDataRemote( aKey, null );
  177.   data.stringValue = aStringValue;
  178.   return aStringValue;
  179. }
  180.  
  181. /**
  182.  * \brief Set a boolean value.
  183.  * Changes the value of the data remote to the boolean passed in, regardless
  184.  *   of its value before.
  185.  *
  186.  * \param aKey - The string identifier for the data to be changed.
  187.  * \param aBoolValue - A boolean value.
  188.  * \return - The new value of the data.
  189.  * \sa DatatRemote
  190.  */
  191. function SBDataSetBoolValue( aKey, aBoolValue )
  192. {
  193.   var data = SB_NewDataRemote( aKey, null );
  194.   data.boolValue = aBoolValue;
  195.   return aBoolValue;
  196. }
  197.  
  198. /**
  199.  * \brief Set an integer value.
  200.  * Changes the value of the data remote to the integer passed in, regardless
  201.  *   of its value before.
  202.  *
  203.  * \param aKey - The string identifier for the data to be changed.
  204.  * \param aIntValue - An integer (or string convertable to an integer) value.
  205.  * \return - The new value of the data.
  206.  * \sa DatatRemote
  207.  */
  208. function SBDataSetIntValue( aKey, aIntValue )
  209. {
  210.   var data = SB_NewDataRemote( aKey, null );
  211.   data.intValue = aIntValue;
  212.   return aIntValue;
  213. }
  214.  
  215. /**
  216.  * \brief Increment the integer value.
  217.  *  Increment the integer value associated with the key passed in. If a ceiling
  218.  *    value is passed in the new value will be no greater than the ceiling.
  219.  *
  220.  * \param aKey - The string identifier for the data to be changed.
  221.  * \param aCeiling - Optional, if specified the data will be at most, this value
  222.  * \return - The new value of the data.
  223.  * \sa DatatRemote
  224.  */
  225. function SBDataIncrementValue( aKey, aCeiling )
  226. {
  227.   // if no ceiling is given use the *ceiling*
  228.   if ( aCeiling == null || isNaN(aCeiling) )
  229.     aCeiling = Number.MAX_VALUE;
  230.  
  231.   var data = SB_NewDataRemote( aKey, null );
  232.   var newVal = (data.intValue + 1);  // getter call
  233.   if ( newVal > aCeiling )
  234.     newVal = aCeiling;
  235.   data.intValue = newVal;            // setter call
  236.   return newVal;
  237. }
  238.  
  239. /**
  240.  * \brief Decrement the integer value.
  241.  *  Decrement the integer value associated with the key passed in. If a floor
  242.  *    value is passed in the new value will be no less than the floor.
  243.  *
  244.  * \param aKey - The string identifier for the data to be changed.
  245.  * \param aFloor - Optional, if specified the data will be no less than this
  246.  *                 value
  247.  * \return - The new value of the data.
  248.  * \sa DatatRemote
  249.  */
  250. function SBDataDecrementValue( aKey, aFloor )
  251. {
  252.   // if no floor is given, use the *floor*
  253.   if ( aFloor == null || isNaN(aFloor) )
  254.     aFloor = -Number.MAX_VALUE;
  255.  
  256.   var data = SB_NewDataRemote(aKey, null);
  257.   var newVal = (data.intValue - 1);  // getter call
  258.   if ( newVal < aFloor )
  259.     newVal = aFloor;
  260.   data.intValue = newVal;            // setter call
  261.   return newVal;
  262. }
  263.  
  264. /**
  265.  * \brief Change the boolean value.
  266.  * The true/false value of the data associated with the key will be reversed.
  267.  *
  268.  * \param aKey - The string identifier for the data to be changed.
  269.  * \return - The new value of the data.
  270.  * \sa DatatRemote
  271.  */
  272. function SBDataToggleBoolValue( aKey )
  273. {
  274.   var data = SB_NewDataRemote(aKey, null);
  275.   var newVal = !data.boolValue;
  276.   data.boolValue = newVal;
  277.   return newVal;
  278. }
  279.  
  280. /**
  281.  * \brief Cause a notification to be fired.
  282.  * The data associated with the key will be modified so that observers will
  283.  *   be called about the change. The actual value of the data should not be
  284.  *   counted on.
  285.  *
  286.  * \param aKey - The data about which the event is being fired
  287.  * \param aKey - The string identifier for the data about which the event is
  288.  *               being fired.
  289.  * \return - The new value of the data.
  290.  * \sa DatatRemote
  291.  */
  292. function SBDataFireEvent( aKey )
  293. {
  294.   var data = SB_NewDataRemote( aKey, null );
  295.   return ++data.intValue;
  296. }
  297.  
  298.